Bandwidth Monitor for DD-WRT
Your here: Main Page / WiFi / DD-WRT Tutorials / Scripting / Bandwidth Monitor for DD-WRT Bandwidth Monitor: General The bw_monitor.sh file is a script which is run on a wrt firmware based router. The script is used to record and generate display information on a per MAC basis. It is been completely re-written but is based on the wrtbwmon script created by Emanual Brucy (http://code.google.com/p/wrtbwmon/). The biggest difference from this script and the original (wrtbwmon) is the amount of data that is recorded and is able to be displayed, and its use of resources (I/O etc). Because of the volume of data that is recorded and displayed, this version is a bit heavier on disk space and RAM (storing data for each day and generating/converting the data to a java script objects). I am in the process of allowing users to turn off the daily usage, and purely record the total usage either periodically (reset day) or continually(as the current wrtbwmon does). THIS IS AVAILABLE IN VERSION 0.6 and above It allows a router administrator to setup users to MAC's (1 to 1), or User Groups to a list of MAC's (1 to many). The script starts of by setting up iptables rules (per IP), and recording download and upload data on a per-day basis (day 1 to day 31). This data will be periodically saved to a usage file, which will be used to publish a java script file, which represents the data contained within the file (but converted into java script objects). This java script output will then be used within an html file for displaying usage data in a friendly and effective manner to users (via a script link). The script supports automatic usage reset and archiving (saving usage file and java script to a history), which can be triggered on any day of the month (at midnight). The script is highly customizable and attempts to limit the amount of I/O by performing many functions within RAM. Future Plans Release History Version 1.0 *Added a new option to show MAC addresses in the html file if a client is Auto Added (showMAC - Option 17) *''Provided very basic logging. This is enabled by supplying a log path and file name (logFilePath - Option 18) *General Code Cleanup Version 0.9 *Allows a user to change between 1000 and 1024 via Query String Parameters. *Added 2 new optional script arguments, Auto Add MAC's, and Bit32 Support. *When the page refreshes, it will keep the usage day and the bytes base you have selected (via query parameters) *Added bc support (Mandatory) *Removed redundant sed global checks (improved performance) *Changed interface.html to monitor.html *removed wanup script and kept startup script ONLY *Fixed up the DNSMASQ to USERS.FILE function to allow more than one underscore ''. *''Added a line to the startup script which allows you to automatically change the javascript path in the html file.'' *''Made changes to the iptables setup methods to ensure rule is always at top of the list and there is ONLY ever 1.'' *''Fixed reset method'' *''Added new exit condition when no users are found in the file.'' *''the setupIPRule function is ONLY called at the very start and every subsequent publish.'' *''FIXED UP HELP WIKI AND SETUP GUIDES http://code.google.com/p/lal-projects/wiki/bw_monitor_setup'' ''Version 0.8'' Changed HTML file now include total usage (down and up) for the 'Day Usage' section. Changed the bytes function to now use base 1000. I am in the process of making this an option value that can be set by the user Bandwidth Monitor: Manual Prerequisites Required Packages and Commands#Linux OS that supports shell scripts #This is designed to run on a router. The following lists what commands are used by the script. YOU must ensure you can run the following commands from your command line. If you cannot, and the command IS NOT optional, then you must install it. Install Packages I am not too sure where you can find all the required packages. The package also sometimes depends on the router model or the linux version so you really need to do some research. I can only provide some links that may guide you: View this thread - http://www.dd-wrt.com/phpBB2/viewtopic.php?t=81432&postdays=0&postorder=asc&start=60 wget http://downloads.openwrt.org/kamikaze/8.09.2/brcm47xx/packages/bc_1.06.94-1_mipsel.ipk ipkg -d root install bc_1.06.94-1_mipsel.ipk Minimum Requirements The minimum requirements depends on how many users/clients you wish monitor and the number machines each client has. As a general guide, please use the following. Each file can also gets read into RAM, so their must be an equal amount of RAM available as well. Also, if you chose to keep the mac_usage data in RAM, the disk space is not required for it. For an average user, I would recommend 50 MAC's to be monitored. This would mean having around 450-550KB of RAM and 600KB of disk. This again depends on if you store usage data on the file system or in RAM and if you keep the last months javascript file (user set) Important Files Required Optional System Generated or Used USAGE DATA The usage data is recorded in the following format: MAC,IP,DOWNLOAD,UPLOAD,DAY USER FILES The user file must be in the following format: MAC,IP,USER,TYPE Example 00:00:00:00:00,192.168.1.1,USER,PC-Upstairs 00:00:00:00:00,192.168.1.1,Room1,User-1-PC DNSMASQ FILES (Setting up users through the Web UI) A typical dnsmasq file will look somthing like this when opened using the 'cat' command: root@DD-WRT:/tmp# cat dnsmasq.conf interface=br0 resolv-file=/tmp/resolv.dnsmasq all-servers leasefile-ro dhcp-script=/etc/lease_update.sh dhcp-lease-max=20 dhcp-option=lan,3,192.168.1.1 dhcp-authoritative dhcp-range=lan,192.168.1.125,192.168.1.134,255.255.255.0,120m dhcp-host=00:00:00:00:00:00,Shouhan_PC,192.168.1.20,1440m dhcp-host=11:11:11:11:11:11,Chris_PC,192.168.1.21,1440m dhcp-host=22:22:22:22:22:22,Makoto_PC,192.168.1.22,1440m dhcp-host=33:33:33:33:33:33,Lal_Dell-eth,192.168.1.30,1440m stop-dns-rebind domain=lan local=/lan/ The system will monitor and convert the file into the users.file format (MAC,IP,USER,TYPE) and place it in the /tmp/ directory as dnsmasq2users.file. Never edit this file as the changes will NOT persist after reboot Using the dnsmasq file does not allow a user to setup the MAC DISPLAY flag (this is being looked into). To define a USER,TYPE via the web UI, the user name entry must be in the following format: USER_TYPE - The underscore represents the delimiter between user/group and type. Example dhcp-host=33:33:33:33:33:33,Lal_Dell-eth,192.168.1.30,1440m The above will be converted into: 33:33:33:33:33:33,192.168.1.30,Lal,Dell-eth HTML TEMPLATE If you change the path of the (web address) of the stored java script page, you will need to also update this page as well. NOTE: This is NOW part of the startup/wanup script (see below) Setup Guide Steps There are a few way to get this running on your system. I will focus on two of them One way is to use persistant storage, such as flash drive or somthing similar (samba, jffs etc) #Downlaod the bw_monitor.sh script and save it #chmod +x the script. This makes it executable #Download the monitor.html file #Create and modify the below script and save it as a startup or a wanup script (this is described in detail in the Startup/Wanup Scripts section below): #!/bin/sh while [ ! -f /tmp/monitor-started.lock ] && [ ! -f /tmp/monitor-stop ]; do if [ ! -f /tmp/www/monitor.html ]; then sed 's/src=.*>/src="http:\/\/192.168.1.1\/user\/user_details.js"><\/script>/' /mnt/monitor/setup/monitor.html > /tmp/www/monitor.html fi /mnt/monitor/setup/bw_monitor.sh 30 3 30 4 /mnt/monitor/setup/users.file /mnt/monitor/mac_usage.backup /mnt/monitor/history/ 1 '' 1 1 1 1 1 1'' if [ ! -f /tmp/monitor-started.lock ]; then sleep 10 fi done The second way to set up a startup script as described above, but instead of storing the bw_monitor.sh and the monitor.html file, you amend the startup script to download them using wget. The following assumes you have NO persistant storage Example #!/bin/sh wget http://code.google.com/p/lal-projects/source/browse/tags/V0.8_wrt-bandwidth-statistics/bw_monitor.sh -O /tmp/bw_monitor.sh && chmod +x /tmp/bw_monitor.sh wget http://code.google.com/p/lal-projects/source/browse/tags/V0.8_wrt-bandwidth-statistics/monitor.html -O /tmp/monitor.html #INSERT CODE TO RESTORE BACKED UP USAGE FILE. SAVED AS /tmp/mac_usage.backup #If not using dnsmasq file echo 'MAC,IP,USER,TYPE' > /tmp/users.file echo 'MAC,IP,USER,TYPE' >> /tmp/users.file echo 'MAC,IP,USER,TYPE' >> /tmp/users.file while [ ! -f /tmp/monitor-started.lock ] && [ ! -f /tmp/monitor-stop ]; do if [ ! -f /tmp/www/monitor.html ]; then sed 's/src=.*>/src="http:\/\/192.168.1.1\/user\/user_details.js"><\/script>/' /tmp/monitor.html > /tmp/www/monitor.html fi /tmp/bw_monitor.sh 30 3 30 4 /tmp/users.file /tmp/mac_usage.backup /tmp/ /tmp/mac_usage.db '' 1 1 1 1 1 1'' if [ ! -f /tmp/monitor-started.lock ]; then sleep 10 fi done rm /tmp/monitor.html Ideally, you would have some sort of cron job that backups the mac_usage.db file (maybe an FTP site etc) and an extra call to place the backed up file back into temp (before the script is started) so it can be restored after subsequent restarts. Script Arguments The bw_monitor.sh script takes in up to 14 arguments. They are as follows and must be supplied in order. Note: All PATH only parameters MUST contain a slash / at the end. e.g. /mnt/monitor/ NOT /mnt/monitor For ALL optional values, you can supply NO value or empty string . This will cause the defaults to be used. Examples Do not copy and past the following examples. It has been formatted for viewing only (contains spaces that it shouldnt). The numbers in brackets refer to the script arguments defined in the table above. bw_monitor.sh 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Example 1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 bw_monitor.sh 30 3 30 4 /mnt/monitor/setup/users.file /mnt/monitor/mac_usage.backup /mnt/monitor/history/ #This will use all the defaults for the optional values. No Logging Example 2 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 bw_monitor.sh 30 3 30 4 /mnt/monitor/setup/users.file /mnt/monitor/mac_usage.backup /mnt/monitor/history/ 1 '' 1 1 1 1 1 1 0 0'' #This example enables ALL optional values, but uses the default javascript path (9), and does not store usage data in a file, its kept in memory (8) Example 3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 bw_monitor.sh 30 3 30 4 /mnt/monitor/setup/users.file /mnt/monitor/mac_usage.backup /mnt/monitor/history/ 1 '' 1 1 0 0 1 1 0 0'' #This example enables all optional values, except for keeping the last javascript file, and backing up the javascrit file to history. It does not store usage data in a file, its kept in memory (8) Example 4 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 bw_monitor.sh 30 3 30 4 /mnt/monitor/setup/users.file /mnt/monitor/mac_usage.backup /mnt/monitor/history/ /tmp/mac_usage.db '' 1 1 0 0 1 1 0 0'' #This example is the same as example 3, BUT we are saving the usage data to a file (8) /tmp/mac_usage.db. Example 5 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 bw_monitor.sh 30 3 30 4 /tmp/dnsmasq.conf /mnt/monitor/mac_usage.backup /mnt/monitor/history/ /tmp/mac_usage.db '' 1 1 0 0 1 1 0 0'' #This example is the same as example 4, BUT we are using the dnsmasq file instead of a custom users file. As mentioned in the USER FILES section, this script will convert the contents of this file and save it as a tmp file dnsmasq2users.file. Example 6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 [18 bw_monitor.sh 30 3 30 4 /tmp/dnsmasq.conf /mnt/monitor/mac_usage.backup /mnt/monitor/history/ /tmp/mac_usage.db '' 1 1 0 0 1 1 0 0 /tmp/bw_monitor.log'' #This example is the same as example 5, BUT we are also using logging Startup/Wanup Scripts A typical setup would copy the html file to the web server, and then initialise (start) the bw_monitor.sh script. For the below example, I continually loop until the monitor-started.lock file is created. I however have include a monitor-stop file in the loop condition as well. If this file exists, it will break the loop. Its main purpose is for those that implement the below in a .wanup script. The below script also allows you to change the javascript script path in the html file. This uses sed and replaces the cp command for moving the html file to the correct location. #!/bin/sh while [ ! -f /tmp/monitor-started.lock ] && [ ! -f /tmp/monitor-stop ]; do if [ ! -f /tmp/www/monitor.html ]; then sed 's/src=.*>/src="http:\/\/192.168.1.1\/user\/user_details.js"><\/script>/' /mnt/monitor/setup/monitor.html > /tmp/www/monitor.html fi /mnt/monitor/setup/bw_monitor.sh 30 3 30 4 /mnt/monitor/setup/users.file /mnt/monitor/mac_usage.backup /mnt/monitor/history/ 1 '' 1 1 1 1 1 1'' if [ ! -f /tmp/monitor-started.lock ]; then sleep 10 fi done Query Parameters When you have the script up and running, you can view the results using the monitor.html file. As well as viewing information on this page, I have supplied a few query parameters that allow to change some of the information And example is below http://192.168.1.1/user/monitor.html?baseSelected=1024 The above tells the page to use 1024 as the bytes conversion base Links dd-wrt - Bandwidth Usage Monitor Thread Project Home